{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# hvPlot.bivariate\n",
    "\n",
    "```{eval-rst}\n",
    ".. currentmodule:: hvplot\n",
    "\n",
    ".. automethod:: hvPlot.bivariate\n",
    "```\n",
    "\n",
    "## Backend-specific styling options\n",
    "\n",
    "```{eval-rst}\n",
    ".. backend-styling-options:: bivariate\n",
    "```\n",
    "\n",
    "## Examples\n",
    "\n",
    "### Basic bivariate plot"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import hvplot.pandas # noqa\n",
    "import numpy as np\n",
    "import pandas as pd\n",
    "\n",
    "x, y = np.random.multivariate_normal([0, 0], [[1, 0.8], [0.8, 1]], 1000).T\n",
    "df = pd.DataFrame({\"x\": x, \"y\": y})\n",
    "\n",
    "df.hvplot.bivariate(data_aspect=1)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Bivariate distribution of penguins bill length and depth\n",
    "\n",
    "This example shows the joint distribution of bill length and bill depth in penguins using a 2D density estimate. Note `colorbar=True` by default."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import hvplot.pandas  # noqa\n",
    "\n",
    "df = hvplot.sampledata.penguins(\"pandas\")\n",
    "\n",
    "df.hvplot.bivariate(x='bill_length_mm', y='bill_depth_mm', width=400)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The plot below displays the contour lines of a bivariate plot overlaid with a scatter plot. The contour lines help highlight the 3 clusters present in the dataset."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import hvplot.pandas  # noqa\n",
    "\n",
    "df = hvplot.sampledata.penguins(\"pandas\")\n",
    "\n",
    "(\n",
    "    df.hvplot.bivariate(x='bill_length_mm', y='bill_depth_mm', width=400, cmap='grey_r')\n",
    "    * df.hvplot.scatter(x='bill_length_mm', y='bill_depth_mm', alpha=0.1, color='green')\n",
    ").opts(show_legend=False) "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `filled` parameter specifies whether the contours should be filled."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import hvplot.pandas  # noqa\n",
    "\n",
    "df = hvplot.sampledata.penguins(\"pandas\")\n",
    "\n",
    "df.hvplot.bivariate(x='bill_length_mm', y='bill_depth_mm', filled=True, cmap='viridis', width=400)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Control smoothing with `bandwidth`\n",
    "\n",
    "You can control the smoothness of the estimate using the `bandwidth` argument that accepts a positive numerical value. Smaller values yield more detail. When not set, the bandwidth is internally computed using Scott's rule of thumb."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import hvplot.pandas #  noqa\n",
    "\n",
    "df = hvplot.sampledata.penguins(\"pandas\")\n",
    "\n",
    "plot_opts = dict(\n",
    "    x='bill_length_mm', y='bill_depth_mm',\n",
    "    colorbar=False, frame_width=200, aspect=1,\n",
    ")\n",
    "df.hvplot.bivariate(bandwidth=0.2, title='bandwidth=0.2', **plot_opts) +\\\n",
    "df.hvplot.bivariate(bandwidth=0.6, title='bandwidth=0.6', **plot_opts)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Control binning with `levels`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import hvplot.pandas  # noqa\n",
    "\n",
    "df = hvplot.sampledata.penguins(\"pandas\")\n",
    "\n",
    "plot_opts = dict(\n",
    "    x='bill_length_mm', y='bill_depth_mm',\n",
    "    colorbar=False, frame_width=200, aspect=1,\n",
    ")\n",
    "df.hvplot.bivariate(levels=5, title='levels=5', **plot_opts) +\\\n",
    "df.hvplot.bivariate(\n",
    "    levels=[0.001, 0.002, 0.004, 0.006, 0.008, 0.01, 0.1],\n",
    "    title='levels as list', **plot_opts\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Control evaluation extent with `cut`\n",
    "\n",
    "`cut` is a factor, multiplied by the smoothing `bandwidth`, that determines how far the evaluation grid extends past the extreme datapoints. When set to 0, the contours are truncated at the data limits."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import hvplot.pandas  # noqa\n",
    "\n",
    "df = hvplot.sampledata.penguins(\"pandas\")\n",
    "\n",
    "(\n",
    "    df.hvplot.bivariate(x='bill_length_mm', y='bill_depth_mm', cut=0, title='cut=0')\n",
    "    * df.hvplot.scatter(x='bill_length_mm', y='bill_depth_mm', alpha=0.2, color='grey')\n",
    ").opts(show_legend=False) "
   ]
  }
 ],
 "metadata": {
  "language_info": {
   "name": "python",
   "pygments_lexer": "ipython3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}
